Help Writer's Assistant for Windows 1.0

Welcome to Help Writer's Assistant for Windows! (HWA/w)

What is HWA/w?

Files you should have

Menu Commands & Parts of the screen

How To...

What's in a Help File?

Error & Help Messages

Text Editor

HWA Commands (formatting codes)

About HWA for Dos

What is Shareware?!?

Why Register?

How to Register

Registration Form

Known Bugs

Disclaimer

Copying Info

Revision History

Future Enhancements

About the Author

How to contact the Author

Programs and books used to write this program

Acknowledgements

Trademarks


What is HWA/w?

HWA for Windows is a visual help file creator for Windows.  But, it is more than that.  It provides everything you need to create help files under Windows.

In the final release of version 1.0 (this is a public pre-release, or beta), you will not have to see any of the funny words with backslashes.  Version 1.0 & 2.0 are shipped to all registered users for free.  You can pay for HWA/w via VISA [image] or via Bank Cheque.

Previously, building help files under Windows had to be done either by coding RTF commands by hand, or by using a word processor that  understands RTF.  There were problems with this.  You had to remember the context string of the help topic you wanted to link to, and you had to enter footnotes.  At the best of times, it was a pain!  Macros helped make the task easier, but it didn't provide everything you need.  HWA for Windows does that!

HWA/w requires:

Microsoft Windows 3.1 or later.

Around 400k of Hard Drive space

1Mb of RAM (4Mb recommended)

The Microsoft Help Compiler (contact the author if you can't find a copy.  See the What's in a Help File? topic for where you might be able to get a copy)

HWA has many powerful and useful features:

HWA/w saves in text format, so you can edit it outside HWA/w if you like

HWA/w allows you to choose a cross reference or definition by picking a topic from a listbox

HWA/w frees you from having to remember what the name of that bitmap file you wanted to insert was.

HWA/w imports text files, so you don't lose all your previous work.

HWA/w allows you to choose, through a dialog box, or from the toolbar the font and font size you want to use.

HWA/w can automatically compile and run your help file for you.

HWA/w can list all the keywords in your file so you can compare and change them.

HWA/w can easily move topics within the help file, thus making it easier for you to reorganise your help file.

HWA/w can automatically assign browse numbers to your topics, thus freeing you from the task of renumbering every time you add a topic.

HWA/w lets you define sets of commonly used keywords which can then be chosen from a drop down list.

HWA/w lets you find and replace text anywhere in the file.


Files you should have

You need Microsoft Windows version 3.0 or later to use Help Writer's Assistant.  You must also have the Help Compiler suppiled with the Windows SDK or Borland Compilers.

Name	 Description

HWAWIN.EXE	 The main program

HWAWIN.HLP	 The help file that explains how to use HWA/w

HWADWN.EXE	 A windows exe file that converts .HWA files to .RTF files

README.TXT	 Last minute information not included in this help file.

HWAWIN.BUG	 Form to fill in and send away if you find a bug.

HWAREG.TXT	 Registration form to send away to become a registered user

CTL3D.DLL	 File for the 3D effect in dialogs.

LEFT.BMP	 Example bitmap

RIGHT.BMP	 Example bitmap

NORMAL.SHG	 Example bitmap

EG1.HWA	 Demonstration file

EG1.HPJ	 A Windows 3.1 help project file for EG1.HWA

TUTORIAL.HPJ	 A Windows 3.1 help project file for the tutorial.

TUTORIAL.KWS	 An example Keyword Set file for the tutorial.

SEARCH.BMP	 Part of a Help search dialog.  Used in the tutorial.


Menu Commands

File Menu

New

Open

Save

Save As

Exit

Edit Menu

Undo

Cut

Copy

Paste

Clear

Select All

Topic Menu

  	 Insert

Before

After

 Move

Before

After

Delete

 Go To

First

Last

Previous

Next

Go To

Extra Information

List Keywords

Text Menu

  	Font

Color

 Style

  	Bold

Italic

Find

Find Next

Find Previous

Replace

Insert Menu

  	 Text File

 Cross Reference

Normal

 With Title

 Defintion

Normal

With Title

 Bitmap

  	Left

Right

Normal

Compile Menu

Run

Make

Options Menu

Auto Browse Seq

Compiler Preferences

Keyword Sets

Create HEADER.RTF

Help Menu

  	Help Index

Register

About

Parts of the screen


File|New

The File|New option will unload the currently loaded file from memory and will make the current page blank.  If you have made changes since the last save, you will be asked to confirm that you would like to create a new document.

Shortcuts:

 Toolbar:

See Also:

File|Open

File|Save


File|Open

The File|Open option allows you to open an existing file for editing.  It displays a dialog box which lists all the files available for opening.  When you choose a file HWA/w will load it into memory so you can edit it.

Shortcuts:

 Keyboard:	 Control+O

 Toolbar:

 Drag a file from the File manager on to HWA/w.

See Also:

File|New

File|Save


File|Save

The File|Save option saves the file to disk.  If the file has not been saved before it will come up with a dialog box that will allow you choose the name and directory to save the file as.  If the file has been saved before, it will be saved to the name and directory already chosen.  The previous version of the file will be overwritten.  If you want to save the file with a different name use the File|Save As command.

Shortcuts:

 Keyboard:	 Control+S

 Toolbar:

See Also:

File|New

File|Open

File|Save As


File|Save As

The File|Save As option brings up a dialog box where you can choose the name and directory to save the file as.  You can also choose the format to save the file in (currently only HWA format).  If you want to save the file without changing the name use the File|Save menu command.

See Also:

File|Save


File|Exit

The File|Exit option will exit the program, and will ask you if you want to save the file if you have made changes since you last saved the file.


Edit|Undo

The Edit|Undo option will undo the most recent change in the current edit control.  If you are unable to undo anything then the option appears grayed.

Shortcuts:

 Keyboard:	 Alt+Backspace


Edit|Cut

The Edit|Cut option allows you to take the text you have selected to the Windows clipboard, where you can later Paste it back into HWA/w or another application.   If you do not have anything selected then the option appears grayed.

Shortcuts:

 Keyboard:	 Control+Del

See Also:

Edit|Copy

Edit|Paste


Edit|Copy

The Edit|Cut option allows you to copy the text you have selected to the Windows clipboard, where you can later Paste it back into HWA/w or another application.  If you do not have anything selected then the option appears grayed.

Shortcuts:

 Keyboard:	 Shift+Insert

See Also:

Edit|Cut

Edit|Paste


Edit|Paste

The Edit|Paste option will take any text on the clipboard and paste it into the currently selected edit control. You can put text on the clipboard from another application or by using Edit|Cut or Edit|Copy.  If you do not have anything selected then the option appears grayed.

Shortcuts:

 Keyboard:	 Control+Insert

See Also:

Edit|Cut

Edit|Copy


Edit|Clear

The Edit|Clear option will remove any selected text from the current box.  It will not move the text to the clipboard.  If you do not have anything selected then the option appears grayed

Shortcuts:

 Keyboard:	 Delete


Edit|Select All

The Edit|Select All option will select all the text in the current edit control.


Topic|Insert|Before

The Topic|Insert|Before option will insert a new topic before the current topic.  If you want the new topic to become the topic after the current topic use Topic|Insert|After. The new topic will be blank and the caret will be in the Title control.

Shortcuts:

 Keyboard:	 Alt+B

See Also:

Topic|Insert|After

Topic|Move|Before

Topic|Delete


Topic|Insert|After

The Topic|Insert|After option will insert a new topic after the current topic.  If you want the new topic to become the topic before the current topic use Topic|Insert|Before. The new topic will be blank and the caret will be in the Title control.

Shortcuts:

 Keyboard:	 Alt+A

See Also:

Topic|Insert|Before

Topic|Move|After

Topic|Delete


Topic|Move|Before

The Topic|Move|Before command will display a list of topics and you pick the topic you would like the current topic to be moved before.  If you would like to move a topic after the current topic use Topic|Move|After.  The current topic will stay the same - but will have moved position in the help file.

See Also:

Topic|Insert|Before

Topic|Move|After

Topic|Delete


Topic|Move|After

The Topic|Move|After command will display a list of topics and you pick the topic you would like the current topic to be moved after.  If you would like to move a topic before the current topic use Topic|Move|Before.  The current topic will stay the same - but will have moved position in the help file.

See Also:

Topic|Insert|After

Topic|Move|Before

Topic|Delete


Topic|Delete

The Topic|Delete option will remove the current topic from the file.  A message box will be displayed confirming you want to delete the topic, and if you answer yes, the topic will be deleted from memory.  If you have made a mistake and you have not saved the file you could load the file again to lose the changes.

See Also:

Topic|Insert|Before

Topic|Insert|After


Topic|Go To|First

The Topic|First option goes to and displays the first topic in the current file.

Shortcuts:

 Toolbar:

See Also:

Topic|Go To|Last


Topic|Go To|Last

The Topic|Last option goes to and displays the last topic in the current file.

Shortcuts:

 Toolbar:

See Also:

Topic|Go To|First


Topic|Go To|Previous

The Topic|Previous option changes the current topic to the topic before it in the file.  If there is no topic before the current one, then the option will appear grayed, and will be unselectable.

Shortcuts:

 Keyboard:	 Control+Pg Up

 Toolbar:

See Also:

Topic|Go To|Next


Topic|Go To|Next

The Topic|Next option changes the current topic to the topic after it in the file.  If there is no topic after the current one, then the option will appear grayed, and will be unselectable.

Shortcuts:

 Keyboard:	 Control+Pg Dn

 Toolbar:

See Also:

Topic|Go To|Last


Topic|Go To|Go To

The Topic|Go To command allows you to change the current topic.  It brings up a dialog box, which has a list box in it.  The listbox displays the names of all the titles of the topics in the current file.  You can choose one and press OK or double-click on a title and it will go to the topic, where you can start working on it.  If you want to go to a particular Topic Number (as used by the Help Compiler) the Topic Number button will allow you to enter the topic number.

Shortcuts:

 Keyboard:	 Control+G

 Toolbar:


Topic|Extra Information

The Topic|Extra Information command allows you to edit information associated with the current topic that is not displayed in the main window.  This information is:

Build Tags:

There are 6 Build Tags per topic

Title Scrolling

If this option is checked then the title area, if scrollbars are available in WINHELP, will scroll out of view.  The default is to have what is called a non-scrolling region at the top of the screen, so that you can always see the title of the topic, even when you are several pages down the topic.  If the topic is going to be linked to by a definition jump, then it has to be have Text|Title Scrolling checked.  This is due to a problem in WINHELP, that if a non-scrolling region is at the top of a topic, and it is jumped to by a definition jump  then it will just display the topic of the title.  This option works around that problem.  It is the easiest way to do it.  If you are using the 3.0 Help compiler this option will be grayed.

Don't Display Title:

If this option is checked the title will not be displayed in the Help Window.  Any Cross-References, Definition links or Keywords  will still work.

Not in Browse Sequence

If this option is checked then HWA for Windows will not automatically assign a Browse Sequence Numberto the topic.  This can be useful for topics which should only be available via hypertext links, for example Definition links.  This option will be grayed if the Options|Auto Browse Seq  is not checked

Shortcuts:

 Keyboard:	 Ctrl+E

 Mouse:	 Double click on the grey background of the main window.

See Also:

Options|Auto Browse Seq


Topic|List Keywords

The Topic|List Keywords command allows you to list and edit all the keywords in your HWA file.  This command is useful to help you to make sure that keywords are spelt correctly or that keywords that should be the same are the same.

The dialog box is based around a listbox where all the keywords are situated, with their topics to their right.  If you double click with the mouse on an item or you press the Edit Keyword button the Edit Keywords dialog box is displayed.

The Exit button will return you to the main window where you can continue editing your help file.


Edit Keywords

The dialog box contains:

Keyword:

This is the keyword you are editing.  You can edit and change the keyword in any way you like.  The normal keyword restrictions apply.  If you want to choose a keyword that is in the a Keyword Set just pick the keyword from the drop down list.

Topic:

This is the title of the topic where the keyword you are editing it.  It is greyed to show you that you are unable to change the title name.  It is there simply to show which topic the keyword is from.

Ok:

The Ok button will save any changes you have made and return to the List Keywords dialog.

Cancel

The Cancel button will ignore any changes and return to the List Keywords dialog.


Text|Font

The Text|Font option will, if you are in either the Main Text or Title edit controls allow you to change the font and size of the text.  You will see the change in font in the boxes, but you will not see the change in size in the title box.  If you check the global change option, it will change all the fonts in the file in the current edit control (Title or Main text)) to be the same through the whole file.  The Toolbar Font Chooser will show you the size and the font of the current edit control(if you are in Title or Main Text).

Shortcuts:

 Keyboard:	 Control+F

 Toolbar:


Text|Color

The Text|Color command allows you to change the color of text in either the Title or Main Text edit control.  It will make the relevant change to the control that you were in before the dialog was opened.

 If you were in the Title control the color of the text in the whole control will be changed.  You will see the color change.

If you were in the Main Text control it will not display in a different color in the Main Text control, but it will be in the color in the help file.  It will look something like this in the Main Text control: \color{Hello}{12}.  The text inside the first curly brackets is the part that is in color.  Inside the second brackets is the color number.  If you later decide to make a larger area of text coloured, just make sure you get both the \color{Hello}{12} and the starting and closing brackets selected, and when you change the rest of the text to a color the \color{Hello}{12} and the brackets will move to enclose the selected text.


Text|Style|Bold

The Text|Style|Bold option will make the selected text bold.  It will not display bold in the Main Text control, but it will be bold in the help file.  It will look something like this in the Main Text control: \bold{Hello}.  The text inside the curly brackets is the part that is bold.  If you later decide to make a larger area of text bold, just make sure you get both the \bold{Hello} and the starting and closing brackets selected, and when you change the rest of the text to bold the \bold{Hello} and the brackets will move to enclose the selected text.

Shortcuts:

 Keyboard:	 Control+B

See Also:

Text|Style|Italic


Text|Style|Italic

The Text|Style|Italic option will make the selected text italic.  It will not display italic in the Main Text control, but it will be italic in the help file.  It will look something like this in the Main Text control: \italic{Hello}.  The text inside the curly brackets is the part that is italic.  If you later decide to make a larger area of text italic, just make sure you get both the \italic{Hello} and the starting and closing brackets selected, and when you change the rest of the text to italic the \italic{Hello} and the brackets will move to enclose the selected text.

Shortcuts:

 Keyboard:	 Control+I

See Also:

Text|Style|Bold


Text|Find

The Text|Find command allows you to find text in your HWA file.  To do this, move to the control you want to find text in (e.g: Title) and choose the Text|Find command.

With this dialog (unlike other dialogs in HWA/w) you are able to edit your file while you have the dialog open.

The dialog contains:

Find What:

This is the text that you would like to search for in the current control.

Match Case:

Check this if you would like the text you are searching for to be compared using case sensitivity.  For example:  You want to find the text HeLLo in your file, and you want to find only the text with exactly the same capitalisation so you would check the Match Case checkbox.

Direction:

This button determines which direction you want to search in.  If you want to go down through the file (from Topic 1 to Topic 30 etc...) have Down selected (default), if you want to go up through the file (from Topic 30 to Topic 1 etc...) have Up selected.

Buttons:

The Find Next button will search for the text in the Direction you have asked it to search.

The Cancel button will exit the dialog and return you to the main window.

See Also:

Text|Find Next

Text|Find Previous

Text|Replace


Text|Find Next

The Text|Find Next command searches for text based on the current selections in the Text|Find or Text|Replace dialog boxes.  It will search Down through the file.

Shortcuts:

 Keyboard:	 F3

See Also:

Text|Find

Text|Find Previous

Text|Replace


Text|Find Previous

The Text|Find Previous command searches for text based on the current selections in the Text|Find or Text|Replace dialog boxes.  It will search Up through the file.

Shortcuts:

 Keyboard:	 Shift+F3

See Also:

Text|Find

Text|Find Next

Text|Replace


Text|Replace

The Text|Replace command allows you to find text in your HWA file and replace it with another piece text .  To do this, move to the control you want to find text in (e.g: Title) and choose the Text|Replace command.

With this dialog (unlike other dialogs in HWA/w) you are able to edit your file while you have the dialog open.

The dialog contains:

Find What:

This is the text that you would like to search for in the current control.

Replace With:

This is the text that you would to replace the Find What text with.

Match Case:

Check this if you would like the text you are searching for to be compared using case sensitivity.  For example:  You want to find the text HeLLo in your file, and you want to find only the text with exactly the same capitalisation so you would check the Match Case checkbox.

Buttons:

The Replace button will search for the Find What text down through the file.  If it finds the text it will ask you to confirm that you want to replace this occurrence of the text with the Replace With text.  Once it has found it once it will stop.

The Replace All button will search for the Find What text down through the file.  If it finds the text it will ask you to confirm that you want to replace this occurance of the text with the Replace With text.  It will continue searching until it can find no more occurrences of the Find What text.

The Cancel button will exit the dialog and return you to the main window.

See Also:

Text|Find

Text|Find Next

Text|Find Previous


Insert|Text File

The Insert|Text File option displays a dialog box that allows you to choose a text file to insert into the current topic.  The text file will be put after where the caret is in the Main Text box.  The dialog box has a check box which you can check if you want HWA/w to insert

 and 	 where it finds a new line a tab respectively.  If you do chose this option loading the text file will take quite a lot longer, so don't panic if the machine appears to be doing very little for a while.  HWA/w writes the new file to disk as a temporary file and reads it back again - the temporary file will be in your TEMP directory and will be deleted by HWA/w when you exit the program.

There is a limit on size of the text file: the text in the box + the text file cannot be greater than 32000 bytes(1 character is a byte).


Insert|Cross Reference|Normal

The Insert|Cross Reference command will create a cross reference jump for you.  You must have the text that you want to be a jump selected. A dialog box will be displayed with a list of topics with context strings.  You can choose one and press OK or double-click on a title and it will insert the required information, and you can continue working.

The jump will look like this: \xref{Hello}{context_string} in the Main Text control. The Hello is the text that you have selected to be a jump.  The context_string is the context string of the topic that you are jumping to.   It will be underlined green in the help file.

Shortcuts:

 Keyboard:	 Control+R

See Also:

Insert|Cross Reference|With Title

Insert|Definition|Normal

Insert|Definition|With Title

Cross-References


Insert|Cross Reference|With Title

The Insert|Cross Reference|With Title command will create a cross reference jump for you.   This command will insert the title of the topic as the jump name - very useful for those Table of Contents, etc... A dialog box will be displayed with a list of topics with context strings.  You can choose one and press OK or double-click on a title and it will insert the required information, and you can continue working.

The jump will look like this: \xref{Hello}{context_string} in the Main Text control. The Hello is the title of the topic that want to jump to.  The context_string is the context string of the topic that you are jumping to.   It will be underlined green in the help file.

Shortcuts:

 Keyboard:	 Alt+R

See Also:

Insert|Cross Reference|Normal

Insert|Definition|Normal

Insert|Definition|With Title

Cross-References


Insert|Definition|Normal

The Insert|Definition option will create a definition link for you.    You must have the text that you want to be a jump selected.  A dialog box will be displayed with a list of topics with context strings.  You can choose one and press OK or double-click on a title and it will insert the required information, and you can continue working.

The jump will look like this:  \defn{Hello}{insert_def} in the Main Text control.  The Hello is the text that you have selected to be a jump.  The context_string is the context string of the topic that you are jumping to.  It will be dotted underlined green in the help file.

The topic you are jumping to should have the Title Scrolling option set in the Topic|Extra Information dialog box.

Shortcuts:

 Keyboard:	 Control+D

See Also:

Insert|Cross Reference|Normal

Insert|Cross Reference|With Title

Insert|Definition|With Title

Definition links


Insert|Definition|With Title

The Insert|Definition|With Title command will create a  definition link for you.   This command will insert the title of the topic as the jump name - very useful for those Table of Contents, etc... A dialog box will be displayed with a list of topics with context strings.  You can choose one and press OK or double-click on a title and it will insert the required information, and you can continue working.

The jump will look like this: \defn{Hello}{context_string} in the Main Text control. The Hello is the title of the topic that want to jump to.  The context_string is the context string of the topic that you are jumping to.   It will be dotted underlined green in the help file.

The topic you are jumping to should have the Title Scrolling option set in the Topic|Extra Information dialog box.

Shortcuts:

 Keyboard:	 Alt+D

See Also:

Insert|Cross Reference|Normal

Insert|Cross Reference|With Title

Insert|Definition|Normal

Definition links


Insert|Bitmap|Left

The Insert|Bitmap|Left option will display a specified bitmap or metafile at the left margin of the Help window. The first line of subsequent text aligns with the upper-right corner of the image and subsequent lines wrap along the right edge of the image. The bitmap will not display in the Main Text edit control but will be displayed correctly in the help file.

Choose a bitmap from the dialog box and HWA/w will insert text like this: \bitmapl{bitmapname}.  The text in curly brackets is the name of the bitmap file.

See Also:

Insert|Bitmap|Right

Insert|Bitmap|Normal

Graphics


Insert|Bitmap|Right

The Insert|Bitmap|Right option will display a specified bitmap or metafile at the right margin of the Help window. The first line of subsequent text aligns with the upper-left corner of the image and subsequent lines wrap along the left edge of the image.  The bitmap will not display in the Main Text edit control but will be displayed correctly in the help file.

Choose a bitmap from the dialog box and HWA/w will insert text like this: \bitmapr{bitmapname}.  The text in curly brackets is the name of the bitmap file.

See Also:

Insert|Bitmap|Left

Insert|Bitmap|Normal

Graphics


Insert|Bitmap|Normal

The Insert|Bitmap|Normal option will display a specified bitmap or metafile in the current line of text. The statement positions the bitmap or metafile as if it were the next character in the line, aligning it on the base line and applying the current paragraph properties. The bitmap will not display in the Main Text edit control but will be displayed correctly in the help file.

Choose a bitmap from the dialog box and HWA/w will insert text like this: \bitmap{bitmapname}.  The text in curly brackets is the name of the bitmap file.

See Also:

Insert|Bitmap|Left

Insert|Bitmap|Right

Graphics


Compile|Run

Registered Users Only

The Compile|Run command will first make the help file, and then it will run WINHELP.EXE loading your help file.  This makes it very easy for you to see your help file without leaving HWA/w.  The help file name is the same as the HPJ file in the Options|Compiling Preferences with HLP as the last three characters rather than HPJ.  The help file will be loaded at the Contents topic.

Shortcuts:

 Keyboard:	 Ctrl+F9

See Also:

Compile|Make

Options|Compiling Preferences


Compile|Make

Registered Users Only

The Compile|Make command builds your help file.  It does so by running HWA for Dos like this:

HWADWN.EXE hwafile.hwa hwawin.rtf keywords.kws

The hwafile is the currently loaded file.  Because HWA/w doesn't have project files (yet) - version 2.0 will have, it can only presume that the file that you want to make is based on the file you are currently editing.  Thus, your HPJ file should use hwafile.rtf (insert your file name as hwafile) as one of the dependent files.  If you have a keyword set HWA/w will use pass that to HWA for Dos so that it will expand your Keyword Sets.

Once HWA for Dos has finished running the command proceeds to run the Help Compiler to compile your HPJ file.  The HPJ file is made outside of HWA/w (version 2.0 will build them for you) - please send your HC documentation for information on what should go into an HPJ file.  The HPJ file that you want to use is defined in the Options|Compiling Preferences dialog box.  HWA/w will run different programs depending on the options you have used in there:

If you have the Help Compiler version set as 3.0 HWA/w will run:

HC30 helpprj.HPJ

If you have the Help Compiler version set as 3.1 HWA/w will run:

HC31 helpprj.HPJ

helpprj is the Help Project file in the Options|Compiling Preferences.

While it is making the file HWA/w will display a dialog box telling you it is compiling.  As soon as both programs have finished running HWA/w will remove the dialog box and let you continue working.

Shortcuts:

 Keyboard:	 F9

See Also:

Compile|Run

Options|Compiling Preferences

Future Enhancements


Options|Auto Browse Seq

The Options|Auto Browse Seq command will automatically number your browse sequences.  This saves you from the having to do the difficult task of changing the numbers in your browse sequence every time that you add a new topic.  It means you can just add and move topics the way you like without worrying about the numbers - HWA/w will do that.

If you do not have this command on HWA/w will save the browse sequences exactly as you have typed them in.  Otherwise, it will save them like this:

If you have characters it will save them, but will ignore anything after the colon (:).  Thus, you can use characters to have different groups of sequences like before, but you just don't have to number them.  HWA/w will number the topics the way that it finds it.  For example: If you have three topics with no characters, HWA/w will number them 0001 to 0003.  If it then finds a topic with cmds the browse sequence number will be cmds:0001.  Then it finds another topic without any text it will be 0004, and then another cmds topic will be cmds::0002.

Because of that it is a good idea to have the topics in the order you want them to be in the help file.  To change the order within HWA/w use the Topic|Move|Before and Topic|Move|After commands.

If you decide that there are some topics that you don't want to have in your browse sequence, you can use the Not in Browse Sequence option in the Topic|Extra Information.  NOTE: That makes changes to the current topic only.

See Also:

Topic|Move|Before

Topic|Move|After

Topic|Extra Information

Browse Sequences


Options|Compiling Preferences

Registered Users Only

The Options|Compiling Preferences command allows you to choose you HPJ path, your Help Compiler version and whether or not you want to delete the Phrase files.

The dialog contains:

Help Project File:

This is where you choose the file that the Help Compiler should compile to make your help file.  The Compile|Run and Compile|Make commands use this file to compile your help file.  Please see your Help Compiler documentation for how to create HPJ files.  The Browse button allows you to choose your HPJ file by picking it from a directory listing.

Help Compiler Version:

This allows you to choose the version of your Help Compiler.  Currently HWA/w only supports 3.0xx and 3.1xx Help Compilers.  You choose this because the Compile|Run and Compile|Make commands run different programs depending on the version you choose.

Delete Phrase Files?

This option will delete a file created by the Help Compiler to speed up compiling.  You would normally only want to that to happen on final releases of the Help File.

See Also:

Compile|Run

Compile|Make


Options|Keyword Sets

The Options|Keywords Sets command allows you to create and edit sets of commonly used Keywords.  The keywords are then available from a drop down list when you choose your keywords for a topic.  A Keyword Set has a title and one or more keywords.  The file in which you store a Keyword Set is called Keyword Sets (becuase there is more than one Keyword Set normally).  The keywords in the main window then display in their drop down list box the titles of your Keyword Sets.  This makes it very easy to use keywords.

The dialog contains:

Listbox:

This is where the Keyword Sets' Titles are displayed.  You can double click on a set to edit it.

Edit:

This allows you to change the Keyword Set that you currently have selected in the Listbox.  It brings up the Keyword Set Edit dialog box.  You can then make any changes to the Keyword Set. Any changes that you do make the Keyword Set Edit dialog (i.e: if you press OK) will be displayed in the Listbox, which will be updated.

Add:

This will create a new Keyword Set in memory.  The Keyword Set Edit dialog will be displayed so you can enter the information for the set and then if you press Ok the Set will be added to the Listbox.

Delete:

This button will delete the Keyword Set selected in the Listbox from memory.  You will be asked to confirm that you to want to Delete the set.

New:

This button will create a new Keyword Set in memory.  The current Keyword Sets will be unloaded from memory.  If the current Keyword Sets has changed since you opened the dialog you will be asked if you would like to save current file. If you press 'Cancel' you will be returned to the dialog.  'Yes' will save the changes to disk (If the file is untitled it will ask you for and directory to save the file in).  'No' will discard the changes.  Once a new file is created you can work on it like any other Keyword Sets.

Open:

This button will bring up a dialog box where you can choose the Keyword Sets file that you want to load into memory.  The current Keyword Sets will be unloaded from memory.  If the current Keyword Set has changed since you opened the dialog you will be asked if you would like to save current file. If you press 'Cancel' you will be returned to the dialog.  'Yes' will save the changes to disk (If the file is untitled it will ask you for and directory to save the file in).  'No' will discard the changes.  Once the Keyword Sets has loaded the titles will be displayed in the Listbox so you can edit the sets.

Exit:

This button exit the dialog and return to the main window. If the current Keyword Set has changed since you opened the dialog you will be asked if you would like to save current file. If you press 'Cancel' you will be returned to the dialog.  'Yes' will save the changes to disk (If the file is untitled it will ask you for and directory to save the file in).  'No' will discard the changes.  After you exit the dialog the Keywords drop down lists will be updated to include all the new or changed Keyword Set titles.


Keyword Set Edit dialog

The dialog contains:

Keyword Set:

This is the title of the Keyword Set - the part that is used in the drop down combo boxes and is used to identify the Keyword Set in the Listbox in the Options|Keyword Sets dialog box.

Keywords:

These are the keywords you want the Keyword Set to contain.  There can be from 1 to 8 keywords.  The keywords can be only 19 characters long.

Ok:

Will exit the dialog and return to the Options|Keyword Sets dialog - saving any changes you have made to the current set in memory (not to disk).

Cancel:

Will exit the dialog and return to the Options|Keyword Sets dialog - ignoring any changes you have made to the current set.


Options|Create HEADER.RTF

This option will create a file named HEADER.RTF.  The file is used by HWA for Dos to work out the fonts on your system, so that it can choose the relevant fonts when asked to.  This should be run the first time you run HWA for Windows, and run again everytime you change the fonts on your system.


Help|Help Index

This option will load the documentation in Windows help format - it can only be read on-line.  It can be read with only the Windows 3.1 help  viewer.

For help on using Windows help select the Using Help from the Help menu of the Help program.

Shortcuts:

 Keyboard:	 F1

 Toolbar:


Help|Register

This is where you register your copy of HWA for Windows.  That is, you have decided that you would like the extra features that you get by registering the product.  So you send your registration form off.  You will receive back, via normal mail a letter which has your user name and serial no on it.  You can then put your user name and serial no into the dialog box.  If you enter them correctly you will be returned to the main window, where you now have all the extra features that are available to registered users only.  The about box will show you your user name.

See Also:

What is shareware?!?

Why Register?

How to Register


Help|About

This option brings up a dialog box telling you the version number, the author's name, your user name (if you are a registered user), and how you can contact him.  It also tells you the windows version required to run HWA/w.


Parts of the screen

The HWA window contains these elements:

Menu Bar

Toolbar

Title edit control

Browse No edit control

Context String edit control

Keywords combo boxes

Main Text edit control

Status Bar:


Toolbar

The following are descriptions and pictures of items on the HWA/w toolbar:

File|New

File|Open

File|Save

Text|Font

Topic|Go To|First

Topic|Go To|Previous

Topic|Go To|Next

Topic|Go To|Last

Topic|Go To|Go To

Help|Help Index


How To

Install & Run HWA/w

Create a help file

Uprade from a previous version


Installing & Running HWA/w

To install HWA/w: Copy all the files to the directory you would like it to live, then move the CTL3D.DLL file into the WINDOWS directory.  You are then able to run HWA.  To run HWA, run the HWAWIN.EXE file, either from the File Manager, or the Program Manager.  HWAWIN.EXE will accept a file name to load on the command line.  The first time you run HWA/w you should go to the Options|Create HEADER.RTF menu item.  The HEADER.RTF needs to be in the same directory as HWA for Dos.


Creating a help file

This topic introduces you to the process of creating Microsoft Windows Help files (.HLP).  It guides you through creating your own simple help file.

A help file is, to put it simply, a document.  It is a document that can be understood by the Windows Help system.  It can include hot spots and links, so it can be a hypertext document.  A help file is normally made to assist a user to complete a task.  It could be to learn to use a program, or to learn to write a letter.  Help files have many uses.

This topic will assist you to learn how to create help files by stepping through creating a simple example help file.  Simply follow the steps and you will end up with a help file that shows most of the parts of help files, and how you might use them.  This topic is also one of the easiest ways to learn how to use Help Writer's Assistant for Windows.  If at any stage you do not understand what part of the screens of the screen the tutorial is taking about please use the Parts of the screen topic.  If you do not understand what parts of the help file it is talking about please use the What's in a Help File? topic.

If you have not already done so please load HWA for Windows as outlined in Installing & Running HWA/w.  If you have already opened a file please use the File|New menu command to create a new file.  While you are working on this tutorial you may find it useful to turn the Help|Always on Top menu item in the Help Application (i.e: what you are reading this in) on.  This will mean that this window doesn't get lost behind the HWA/w window while you are working on the tutorial.

Before we start writing the help file it is a good idea to turn on a few features that we will use during this tutorial.  Please turn the Options|Auto Browse Seq menu item on (that is so that it has a check mark next to it).  Please go into the Options|Keyword Sets dialog box and click on the Open button.  From the Open dialog please choose the file TUTORIAL.KWS and press Ok.  Please press Exit to exit from the Options|Keyword Sets dialog.  You will learn about why you choose those options later in this topic.  Please also choose the Options|Create HEADER.RTF menu item.  This will create a file that will be used by HWA for Dos later on in this tutorial.

We will now create our first topic.  A topic is much like a page in a book.  Our first topic be will much like a contents page in a book.  It will be the contents topic of our help file.

If your caret is not currently in the title edit control please press Alt+L  The title for this topic is "Contents".  Please type "Contents" into the title control.

Because this is the contents topic we would like the user (the reader of the help file) to go to another topic before being able to use the Browse Buttons (<< and >>on the Windows Help button bar) which make it easy to move between related topics.  The title doesn't have any related topics.  Because we don't have to worry about numbering Browse Sequences (because Options|Auto Browse Seq is on) HWA/w needs to know when a topic shouldn't put a topic in the Browse Sequence.  To do this either double click on the grey background of this main window or choose the Topic|Extra Information menu item.  This will bring up a dialog.  Please click the Not in Browse Sequence option.  A check mark should appear in the box next to the option.  Press Ok when the check mark is there.

Because we don't have to enter a browse sequence number you can press tab twice to get from the Title control to the Context String control.  The context string is very important as it tells the Help Compiler what the name of the topic really is.  The Help Compiler will let you have two titles the same in a file, but you can not have two context strings the same.  In this case please type "Contents" as the context string.  The Help Compiler will use this topic as the contents when it compiles the help file because it is pointed to in the TUTORIAL.HPJ help project file.

As you can see from the Button Bar in the Help application you can easily go to the Contents topic of the Help file by clicking on the Contents button.  The Search(Index under Windows NT) button is where the Keywords for the Help File can be used.  The Search button makes it easy to find a topic because you can choose from a list of Keywords.  Because it is easy to go to the Contents there is no need to let users search for it so we will not enter any Keywords for this topic.

Please Press Alt+M to go to the Main Text control.  Any text which is underlined like the M in Main Text is there to tell you that you can press the Alt Key and that letter at the same time to go to the control after the text.  Please type the following into the Main Text control: "Welcome to our help example.  This file was made using Help Writer's Assistant for Windows 1.0."  Please press Enter (Return on some keyboards) twice .  You will notice that HWA/w has inserted a \par in text where you have pressed Enter.  This is the same as a new line.  It is used by the Help Compiler to know when to start a new line.  Please continue typing:  "This is the contents topic, the first topic a user will see in the help file."  Press Enter.  Please type: "Topics:".  Because you often want parts of the text in a topic to stand out HWA/w allows you to make text Bold or Italic.   Select the text you have just typed in by pressing Shift+Home.  Now please press Ctrl+B or choose the Text|Style|Bold menu item.  The text should now look like this. \bold{Topics:}.  The \bold tells HWA for Dos to make the current text bold in the help file.  The text in the brackets is the bold text.

Currently you don't have any topics to list so for the moment you have now finished your first topic!!  Before we start working on the next topic it would be a good idea to save the file to disk.  Please click on the save toolbar item ( [image]) or choose the File|Save menu command.  This will bring up a dialog where you can choose where to save the file.  Please save it in the same directory as you are storing HWA/w and name the file TUTORIAL.HWA.  Next time you choose File|Save you will not be asked for the file name as you have already told it the required name.  Everytime that we begin a new topic or learn a new task it is a good idea to save the file so that if you make a mistake you can go back to the saved version and try again.

Now it is time to create our second topic.  This topic is based around some of the reasons for using Windows Help as part of your application.  It shows many of the uses for Windows Help.  To create a new topic after the current topic use the Topic|Insert|After menu command or press Alt+A.  You should now have a blank topic in front of you.

Please type in the title as "Why use Windows Help files in an application??".

The Browse Sequence Number is "wh" - HWA/w will add a number to the topic.  There will be related topics so there will be more than one wh.

The Context String is "why_winhelp"

The keyword for this topic will be one of the Keyword Sets.  Please move to the first Keyword control by pressing Alt+K.  Please press F4 to drop down the list of Keyword Set names.  Please use the cursor keys to select the "What is Help" item.  In the Help file this will be expanded to use the Keywords in the Keyword Set rather than the title.

The Main Text is (every time you see \par you should press enter):  "Ease of access for the user:\par

With context-sensitive help (that is where the user can press F1 to get help on the current dialog or menu item) the user has immediate access to help on what he/she is doing, making it easier to learn as they go.\par

Ease of finding information for the user:\par

The search dialog provides an easy way for users to find information on a topic."   Now it would be a good idea to provide a picture of a search dialog.  One is provided in your HWA/w product.  It is SEARCH.BMP.  To include it on the left of the help window of the next line choose the Insert|Bitmap|Left command (you don't need to press Enter.  The Help compiler will put in on the next line regardless.).  Please choose the file from the dialog and HWA/w will insert the necessary text.  It is as simple as that to insert a bitmap using HWA for Windows - you don't even have to remember the directory or file name as you can search for them easily! Please continue :"\par

Ease of  programming:\par

With HWA/w Windows Help creation - a complex task, is made much easier - even visual and enjoyable!  HWA provides many options that users of most other help writing software could only dream about.  For example:  The ability to choose the topic that you want to jump to via a list of topics."

We want to make the headings stand out.  We have already learnt about bold but you can also use Italic text.  Let us say that we want to make the  "of" in "Ease of programming" italic.  With HWA/w that is very easy to do.  Please select the word "of" (your Windows documentation will explain how to select text in Windows) and press Ctrl+I or choose the Text|Style|Italic menu item.  Now the line should look like: "Ease \italic{of} programming:\par".  However, you have now decided that you want to make the whole line italic.  Please select the whole line (but not the \par - if the \par was selected HWA for Dos would not compile your file).  Now make the text italic.  You will notice that the \italic{ and the } have moved to encompass the whole text.  This is also true of bold and of color - which we will cover later.  All you need to do is make sure that you have the \italic{ and the } somewhere in the selected text and they will move.  Please make the "Ease of access for the user:" and "Ease of finding information for the user:" bold text.

That now finishes our second topic - you have now learnt to make text bold and italic, to create new topics and to insert bitmaps.

Please create a new topic (after the current topic).  This topic will be linked to other topics via a definition link (more on that later).  This topic will have a title of "What is Windows help??" no Browse Sequence number (i.e: like the title - use the Topic|Extra Information dialog box) and while you are in the Topics|Extra Information dialog box please turn on the Title Scrolling item.  This is required for topics that are going to have definition links.  The Context String is "what_winhelp" The main text for this topic is: "Windows help is a part of Windows which is easy for the user to access and understand because Winhelp looks the same for every application.  Windows Help can be used for more than just Help files for applications however - it can be used for complete documents that you would like to be able to read on line - there are many possible uses for Windows Help."

Please create a new topic  (after the current topic).  This topic will have a title of "What is HWA/w for then??" and Browse Sequence Number of "wh" and a Context String of "what_hwaw".  The Keyword will again be "What is Help"  Please move to the second Keyword control and choose the "Why use Help" keyword set..

The text for this topic is: "HWA/w is a very powerful but simple way to create Windows Help files.   HWA/w provides an easy to learn interface with a very powerful engine - making it easy enough for new users to write help files, but also powerful enough to be used to write help files for major applications.  HWA/w is the easy way to write Windows Help files.\par

\par"

It would be really useful for the user to find out what Windows help files were if they didn't already know.  We have already created a topic which explains what Windows help files are so all we need to do is create a definition link.  A definition link is where the topic that you want to look up is displayed in a smaller window.  The text that is linked to the Definition topic is displayed in dotted underlined green in the help file.  To create a definition link please select the words in the first sentence "Windows Help".  Please press Ctrl+D or choose the Insert|Defintion|Normal menu item.  From the list of  topics to link to, choose the "What is Windows help??" topic.  The area should now look like this "\defn{Windows Help}{what_winhelp}"  The text in the first set of  brackets is the text you want displayed in the Help File as dotted underlined green.  The text in the second set of brackets is the topic that you want to link to - in this case "What is Windows help??"

Please now add at the bottom of the main text: "See also:\par

Why use Windows Help files in an application??"

"See also:" should be in bold.  Now we want to allow the user to go to the "Why use Windows Help files in an application??" topic.  Because we want it to replace the current topic and not just come up in another window we use a cross reference link.  Cross Reference links use underlined green text.  To create a cross reference link select the "Why use Windows Help files in an application??" text and press Ctrl+R or choose the Insert|Cross Reference|Normal menu item.  From the list choose the topic we want to link to (Why use Windows Help files in an application??).   The area should now look like this "\xref{Why use Windows Help files in an application??}{why_winhelp}"  The text in the first set of  brackets is the text you want displayed in the Help File as underlined green.  The text in the second set of brackets is the topic that you want to link to - in this case "Why use Windows Help files in an application??"

Because we would like to have a neat and organised HWA file and we like to have related groups of topics together in the HWA file we will move the "What is Windows help??" topic after the "What is HWA/w for then??" topic.  To do this we need to go to the topic that we want to move.  On the toolbar just below the menu bar there is a Go To button ( [image]) - alternatively you can use the Topic|Go To|Go To menu item.  This will bring up a dialog box which lists all the topics in the file.  Either click on (or move to using the cursor keys) the "What is Windows help??" topic and press Enter or double click on it.  The topic should be now be displayed.

To move the topic choose the Topic|Move|After menu item.  From the list of topics please choose the topic that you want it to go after - in this case the "What is HWA/w for then??".  When you press Ok the topic will still be selected, but it will have moved within the HWA file.  This command makes it very easy to organise your help file.

Now it is time to return to the contents topic.  Because the contents topic is the first topic we can use the button on the toolbar ( [image]) or choose the Topic|Go To|First.  (If you wanted you could use Go To)  You should now be on the Contents topic.  We have now created 4 topics.  The first topic - Contents is displayed automatically but how can we get to the other topics we have made??  We could use the Search dialog box, but that is a bit of a pain to do to change to every topic.  So we can use cross references.  Please move your caret to after the } following topics and press Enter.  Because we have such long titles it is more likely that we would make a mistake if you typed them all out so you can use Alt+R or the Insert|Cross Reference|With Title menu item.  This brings up a dialog the same as Insert|Cross Reference|Normal.  Choose the "Why use Windows Help files in an application??" topic.  This command is different than Insert|Cross Reference|Normal however - when you press Ok the text in the first brackets is not the text you had selected (normally for this menu item you wouldn't select any text) but the title of the topic that you chose (in this case "Why use Windows Help files in an application??").  This makes it even easier to add cross references.  Please add a cross reference to the "What is HWA/w for then??" topic on the line below the "Why use Windows Help files in an application??"

Currently we are only using one font in our whole Help file - and it looks boring.  HWA/w provides more than one way to change your font.  We will introduce both.  Please go to the Contents topic and put your caret into the Title control.  We would like to change the title font.  Choose the Text|Font menu item.  The dialog box that is displayed is the same as the font dialog that you will see in other Windows applications except this dialog  has a check box to globally change the font.  Please turn this option on.  It will mean that the font changes that we will make will be applied to all titles in this file. (i.e: Global change sets the font of the current control the same everywhere in that control (e.g:Title)in the file.)

Please change the font to Arial at 20 points.  Press Ok.  All the titles in the file will be changed to Arial at 20 points.  Now we decide that we would like the Contents topic to have a title at 24 points.  It is very easy to change the font to reflect this.  On the toolbar are two drop down combo boxes ( [image]).  The first is the font name, the other is the font size.  Because we already have the correct font selected all we need to do is select the number 24 in the drop down box.  The title will only reflect the changes made to the font, not the size but you can easily see the size by looking at the size combo box.  The Main Text control will show both size and font changes.Please now change the font of all the main texts to Times New Roman at 10 points.  Please change the size of the contents Main Text control to 12 points.

Please go to the "Why use Windows Help files in an application??" topic.  We would like to highlight some parts further.  Put the caret into the Title control.  Choose the Text|Color menu item.  A dialog box will be displayed with 16 colors to choose from.  Black should currently be selected.  Please change the selection to Navy.  The text color should now be Navy in the Title edit control.  We also want to highlight that HWA/w is the visual and enjoyable way to write help files.  Please select the word "visual" in the "Ease of programming:" section.  Again choose the Text|Color menu item.  Select the color dark purple this time.  Press Ok.  HWA/w will insert text which will look like \color{visual}{6}.  The text in the first set of brackets is the text to be colored.  The number in the second set of brackets indicates the color number.  Select the word "enjoyable".  This text should be Red.

You have now completed your first help file!  Please make sure that you have saved your file (File|Save) before continuing.  We have only touched the surface of the power of HWA/w and Windows Help files.  Please browse through the rest of this help file to learn more about the powerful features of HWA/w.

Now that we have finished the help file we need to compile it so that we can view it and see our work.  If you are a registered user this is VERY easy.  Please follow the following steps: Choose the Options|Compiling Preferences menu item.

In the dialog please press the Browse button and choose TUTORIAL.HPJ.

Please set the Help Compiler radio button to 3.1.

If you want it to compile faster the second time you compile the project please have the Delete Phrase files option off.

Now all you need to do is choose the Compile|Run menu item and HWA/w will do all the work for you.

If you have not yet registered, Compiling will require a little more work: Choose the File|Run menu item from the Program Manager (or the shell you are using).  Type "hwadwn.exe TUTORIAL.HWA TUTORIAL.EXE TUTORIAL.KWS".  Please see the Compile|Run help for information on what this command line does.  Please put a path name in front of each of the arguments if hwadwn.exe is in a different directory than the tutorial files. Run the MS-Dos prompt. Change to the directory where you have stored the tutorial files. Type: "hc31.exe tutorial.hpj" to compile the help file. Return to windows Run the Winhelp application.  Use File|Open to open tutorial.hlp.

This finishes the tutorial.  Please enjoy continuing to learn how to write Windows Help files using Help Writer's Assistant for Windows!


Upgrading from a previous version

Welcome to Beta III of HWA/w.  Thank you for using HWA/w before.  This new version has many new features.

These include:

HWA/w has been rewritten using the Microsoft Foundation classes.

HWA/w now allows you to change your font from the toolbar.

HWA/w can now automatically compile and run your help file for you. (Registered users only)

HWA/w can now list all the keywords in your file so you can compare and change them.

HWA/w can now easily move topics within the help file, thus making it easier for you to reorganise your help file.

HWA/w can now automatically assign browse numbers to your topics, thus freeing you from the task of renumbering every time you add a topic.

HWA/w now lets you define sets of commonly used keywords which can then be chosen from a drop down list.

HWA/w now lets you find and replace text anywhere in the file.

HWA/w now lets you have text up to 32k in size in your files.

The Text|Title Scrolling menu item has moved to the Topic|Extra Information dialog.

HWA/w now lets you use colors anywhere in your file.

There are many other features.  Please look through the menu and this help file for more information.

To uprade your copy please make sure that you have deleted HWAWIN.EXE and HWADWN.EXE from the previous release.  You can install all other files over the old versions.


What's in a Help File?

A help files can range from the very simple to the very complex.  The following topics try to explain a little bit about what you can find in a help file and how you can achieve it in HWA for Windows.  To learn how to create a help file please use the Creating a help file topic.  If you would like more information on help files it is recommended that you get a copy of the Help Authoring Guide: HAG.ZIP (Windows help format) or WHAG.ZIP (Word for Windows format).  It goes into far more detail than could be done here and includes a copy of the Windows Help Compiler..

Topics

Titles

Context Strings

Browse Sequences

Keywords

Build Tags

Cross-References

Definition links

Graphics


Topics

A Help file is made up of topics.  A topic is like a page in a letter and there are many topics in one help file.  A topic should focus on one specific area, for example this topic, Topics.  There are many other topics in this help file, but this topic focuses only on the task of explaining Topics.  A topic can include text or graphics or hypertext links (or one or more of these options).  The text in a topic can be at maximum 64k, but HWA/w can only handle 32k of text per topic.  It is recommended that you keep topics short, as users don't like to read long topics so break up long topics into several shorter topics.  Every help file has a Contents topic.  The Contents topic is like a table of contents in a book.

You organise your topics and present them the way that you are happy with, as writing help files is an art, and the author chooses the way he or she likes to write them.

What is in a topic?

Each topic MUST contain:

A Title

Each topic can contain:

A Context String

A Browse Sequence Number

Keywords

Build Tags

In the main text section it can contain:

Text, which can be:

 Bold

 Italic

 or no formatting.

Hypertext links:

 Cross-References

 or Definition links

Graphics


Titles

Titles apear in the Bookmark menu and in the "Topics Found" list.  HWA/w requires every topic to have a title.  If you do not want the title displayed in the topic use the Don't Display Title option in the Topic|Extra Information dialog.  A title is normally displayed in a non scrolling region (use the Title Scrolling option in the Topic|Extra Information dialog if you want it to scroll), and is in bold type.

Restrictions:

HWA/w limits titles to 99 characters.

The title can not be formatted, other that have a font and size assigned to it.


Context Strings

Context Strings uniquely identify each topic in the help file.  There can be no context strings the same within the help file.  A context string is not required, however if the topic is being jumped to, the topic must have a context string.

Restrictions:

Context Strings are not case-sensitive.

Context Strings can contain the alphabetic characters A-Z, the numeric character 0-9, and the fullstop (.) and underscore (_).

HWA/w limits the size of a context strings to 18 characters.


Browse Sequences

The << and >> buttons on the button bar of the Help application allow the user to move back and forth between related topics, like moving between pages in a book.  The order that the topics are in is called a browse sequence.  The sequence is defined by numbers, which are entered by the help author into the browse sequence box.

When creating browse sequences the author should attempt to create a sequence that the user would find logical if they were browsing through the help file using browse sequences only.

A browse sequence number is made up of a list name followed by a colon and a sequence number.  e.g: commands:005.  It is a good idea to have the sequence numbers increasing in increments of 5(or more if you want) in case you decide to add more topics later.  The help compiler doesn't worry about skipped numbers.  It does, however look sort the browse sequences as ASCII, rather that as numerical figures.  Because of this, commands:100 would come before commands::95.  By renaming the later to commands:095 it would come before commands:100, this is because the help compiler is looking at the first two digits.

NOTE: Because of this problem the HWA/w has the ability to automatically number your browse seqences for you.  The Options|Auto Browse Seq command will turn this option on.  You then don't have to worry about entering numbers for your browse seqences, just (optionally) character strings and HWA/w will number them for you.

Restrictions:

HWA/w limits the browse sequence to 17 characters.


Keywords

Keywords are used by the Help application to allow users to search for topics.  The keywords entered for the topic are displayed in the search dialog box(in the Help application), and when the user chooses a keyword the topics they are linked to are displayed in the dialog.  It is a good idea to give most topics Keywords, as it is often the fastest way for a user to get to a topic.

HWA/w allows you to have up to eight keywords in a topic.  You can store sets of commonly used keywords that are then pickable from a drop down list by using Keyword Sets.  You can have up to 64 keywords by using Keyword Sets

Restrictions:

Keywords can include any character except for the semicolon (;).

Keywords are unformatted.

Keywords are not case-sensitive.

Any punctuation (other than a semicolon) can be used.

HWA/w limits the length of a keyword to 19 characters.


Build Tags

Build tags are strings you can assign to a topic to include or exclude the topic from a build.  HWA/w allows each topic to have up to 6 build tags.  Build tags are optional and most help systems won't need them.  They allow you to have different versions of one help file without having many different source files.  Any topic which doesn't have a build tag will always be included in a topic.

To assign a build tag use the Topic|Extra Information dialog box.

Please see your Help Compiler documentation for how to use build tags within a HPJ file.

Restrictions:

Build tags are not case senisitive

Build tags can not have spaces or semicolons.


Cross-References

Cross-references (or jumps) allow you to jump from one help topic to another.  Cross references can be a good way for the user to get to related information easily.  Cross references appear in underlined green in the help file.

To add a cross-reference:

Create a topic that you want to jump to.

Add a Context String to the topic you want to jump to.

Use Insert|Cross Reference|Normal or Insert|Cross Reference|With Title to create the jumps.


Definition links

Most help files have words or phrases that a user may not understand.  Definition links allow the user to click on a word and display a definition.  The author of the help file decides which words to define.  You could also display a hint or information that otherwise may not be known.

To add a definition link:

Create a topic that defines the term.

Add a Context String to the topic you want to link to.

Use Insert|Definition|Normal or Insert|Definition|With Title to create the link.


Graphics

Graphics are an important part of help files.  "Pictures can tell a thousand words" so graphics can be useful in your help files as well.  Users will find a graphic useful to engrave what you are explaining in their minds.  Because Windows is a visual environment it can be very helpful to see what is being discussed.

Windows Help will accept graphics in any of these formats:

.BMP

Windows 2.x bitmap

.DIB

Windows 3.x bitmap

.SHG

Windows Help hypergraphic bitmap

To insert a bitmap that will be displayed in the middle of the text, [image] like a character, use the Insert|Bitmap|Normal menu command.

To insert a bitmap that will be displayed to the left of the text, [image] use the Insert|Bitmap|Left menu command. The text will wrap around the right side of the graphic.

To insert a bitmap that will be displayed on the right of the text, [image] use the Insert|Bitmap|Right menu command.  The text will wrap around the left side of the graphic.

If a file containing a metafile is specified, the file must contain a placeable Windows metafile; the Help Compiler will not accept standard Windows metafiles. Furthermore, Windows Help sets the MM_ANISOTROPIC mode prior to displaying the metafile, so the placeable Windows metafile must either set the window origin and extents or set some other mapping mode.


Error & Help Messages

<filename> has changed.  Save file before closing?

<filename> has changed.  Save file before compiling?

Already making a help file.  Please wait until completed and then try again.

Are you sure you want to delete this Keyword Set: <keywordset>?

Are you sure you want to delete this topic: <topicname>?

Copying a <structurename> structure failed.  Please free up some memory and try again.

File <filename> is not an HWA Keyword Set File.

File <filename> too large.

Keyword Sets <filename> has changed.  Save file before creating new file?

Keyword Sets <filename> has changed.  Save file before exiting dialog?

No Help Project file has been chosen from the Options|Compiling dialog box.  Please chose a project

Problem locking memory.  Please exit and reload program.

Replace this occurance of '<string>'?

Search string '<string>' not found.

The current file is "Untitled".  Untitled files can not be compiled.  Please save the file.

There are no keyword sets in file <filename>.

There are no topics in file <filename>.

Too many topics for unregistered version.  Please register.

Unable to allocate memory.  Please free up some memory and try again.

Unable to close file <filename>.

Unable to create edit control <editcontrol>.

Unable to create font.

Unable to create static control <staticcontrol>

Unable to create temporary file.

Unable to execute <programname>.  Please put in the current directory or on the path and try agan

Unable to free memory.  Please exit and reload the program.

Unable to open file <filename>.

Unable to sort out the names of fonts on your system.

You have not entered a name for the current Keyword Set.  A name is required.

You have not entered any keywords for the Keyword Set.  At least one keyword is required.


<filename> has changed.  Save file before closing?

The message is informing you that you have made some changes to the file that is currently loaded, and would like to know if you would like to save the changes you have made.


<filename> has changed.  Save file before compiling?

The message is informing you that you have made some changes to the file that is currently loaded, and would like to know if you would like to save the changes you have made.


Already making a help file.  Please wait until completed and then try again.

This message is informing you that a help file is already being made, and you are unable to run or make the help file while it is already being made.


Are you sure you want to delete this Keyword Set: <keywordset>?

This message is asking you if you would like to delete the keyword set <keywordset>.  If you delete the keyword set you will not be able to bring it back again.  If you would like to delete the Keyword set please press "Yes", otherwise press "No".


Are you sure you want to delete this topic: <topicname>?

This message is informing you that <topicname> is about to be deleted.  When a topic is deleted you can only get it back if you load the file again, in which case you will lose the changes you may have made since it was last File|Savesaved.  If you don't want to delete the topic press the No button.  If you do want to delete the topic press Yes.


Copying a <structurename> structure failed.  Please free up some memory and try again.

This message is informing you that a memory object was unable to be copied.  Try completing the task again, and if it still fails exit and reload the program.


File <filename> is not an HWA Keyword Sets File.

This message is informing you that the file that you have tried to open is not in the HWA Keyword Set File Format.  Please open another file that is in the HWA Keyword Set File Format.


File <filename> too large.

This message is informing you that the file you have selected from Insert|Text File is too large for the text editor.  Files are not able to be greater than 32k.


Keyword Sets <filename> has changed.  Save file before creating new file?

This message is informing you that the Keyword Set File you are working on has changed since you entered the Options|Keyword Sets dialog box.  If you would like to save the changes press "Yes" otherwise press "No".  If you want to stay in the dialog box press "Cancel".


Keyword Sets <filename> has changed.  Save file before exiting dialog?

This message is informing you that the Keyword Set File you are working on has changed since you entered the Options|Keyword Sets dialog box.  If you would like to save the changes press "Yes" otherwise press "No".  If you want to stay in the dialog box press "Cancel".


No Help Project file has been chosen from the Options|Compiling dialog box. Please chose a project

This message is informing you that there is no project selected to be compiled.  Please choose a file in the Options|Compiling Preferences menu.


Problem locking memory.  Please exit and reload program.

This message is informing you that a memory object was unable to be locked - i.e: it is unusable.  It is unlikely that this could happen, but you will need to exist and reload the program.


Replace this occurance of '<string>'?

This message is informing you that a copy of the text you are searching for was found and the program would like to know if you would like to replace it with the replacement string you have defined.  If you do, press "Yes", if you don't press "No".  If you would like to stop searching altogether press "Cancel"


Search string '<string>' not found.

This message is informing you that the string you have tried to find could not be found in the section of the file you are looking in.


The current file is "Untitled".  Untitled files can not be compiled.  Please save the file.

This message is informing you that the file you are working on has not been saved and because it does not have a name HWA for Windows is unable to compile and run your help file.  Please save the file and try again.


There are no keyword sets in file <filename>.

This message is informing you that the Keyword Set file you have tried to open doesn't contain any keyword sets.  Please try and open another file.


There are no topics in file <filename>.

This message is informing you that the file that you have selected for opening  has no topics in it.  Please select another file for opening.


Too many topics for unregistered version.  Please register.

This message is informing you that you can't have more than 20 topics in a help file if you are unregistered.  Please register.


Unable to allocate memory.  Please free up some memory and try again.

This message is informing you that there is not enough memory to allocate memory, or there was a problem while allocating memory.  In order for the program to be able to allocate more memory you will need to close down any other running programs.


Unable to close file <filename>.

This message is informing you that the file that has been opened , saved or created is unable to be closed.  In most cases, this will mean that any data written to the file will be lost.


Unable to create edit control <editcontrol>.

This message is informing you that the edit control window named <editcontrol> was unable to be created.  Please exit the program and reload.  If the problem continues please exit and reload Windows.


Unable to create font.

This message is informing you that the font you have chosen can not be created.  This is most likely due to lack of memory, or the font not existing.


Unable to create static control <staticcontrol>

This message is informing you that the static control window named <staticcontrol> was unable to be created.  Please exit the program and reload.  If the problem continues please exit and reload Windows.


Unable to create temporary file.

This message is informing you that HWA/w was unable to create a file to store information temporarily.  Please free up drive space and try again.


Unable to execute <programname>.  Please put in the current directory or on the path and try again

This message is informing you that the <programname> HWA/w required to compile your project was unable to be found.  Please move the file from on to your path or into the directory HWAWIN.EXE is in.


Unable to free memory.  Please exit and reload the program.

This message is informing you that a memory object was unable to be discarded.  Please exit and reload the program.


Unable to open file <filename>.

This message is informing you the file that you have selected for opening , saving  or creating  is unable to be opened.  This may be due to the file not being able to be found.


Unable to sort out the names of fonts on your system.

This message is informing you that the HEADER.RTF  file was unable to be created because windows was unable to work out the font names.


You have not entered a name for the current Keyword Set.  A name is required.

This message is informing you that the Keyword Set you are working on has not been assigned a name.  Please enter a name, as it is required for a Keyword Set.


You have not entered any keywords for the Keyword Set.  At least one keyword is required.

This message is informing you that you need at least one keyword in your Keyword Set.  Please enter a keyword or press "Cancel" and lose the changes you have made in the Keyword Set Edit dialog dialog box.


Text Editor

The current text editor is just a windows edit control.  Of course, this means that is has all the limitations of an edit control: 32k buffer limit, only  one font, and the list goes on.  A visual text editor is currently being worked on, and will be added to beta IV.  There is a lot of work in creating such an editor, but users have asked for a beta, so I have delivered a beta, minus the text editor.  The text editor will allow you to see bold as bold, to see cross references in green, etc...  The current way it is done may suit some people, but I intend to get a real editor in as soon as possible.   The current text editor will add in the correct commands when you press the tab and enter keys.   Note:If you delete parts of an HWA code, not only will the windows version ignore it, but the Dos version will tell you it is a problem...


HWA Commands (formatting codes)

This is a list of commands you can use in HWA for DOS and for Windows.

\topic{Name}	 - start a new topic with the specified name.

\topic{Name}{CS}	 - start a new topic that has a context string.

\topic[tags]{Name}	- start a new topic that has extra build tags.

\topic[tags]{Name}{CS}	 - start a new topic that has a context and build tags.

\keyword{keywd}	 - specify a keyword for the current topic.

\browse{seqno}	 - specify a browse sequence number for this topic.

\nodup	 - use within the "Name" in a "\topic" command where the name mustn't be duplicated for display.

\xref{jump}{CS}	 - generate a cross-reference jump with its context.

\defn{name}{CS}	 - generate a definition term with its context.

\bitmap{name}	 - insert the file "name" here

\bitmapl{name}	 - insert the file "name" on the left

\bitmapr{name}	 - insert the file "name" on the right

\bold{words}	 - render "words" in a bold font.

\italic{words}	 - render "words" in an italic font

\font{name}	 - change to another font from now on.

\tab	 - output a tabbing command to the RTF file.

\par	 - force a paragraph break here.

\fontsize{num}	 - set the fontsize to "num" half points (default 20).

\bscroll	 - makes the title scrollable

\color{num}	 - uses a color from the colortable.

\titleclr{num}	 - makes the title a color from the colortable.

\nobrowse	 - HWA/w ONLY - this is when a topic shouldn't be auto numbered.

One or more blank lines indicates a paragraph break.  Any characters beginning with "%" and continuing to the end of a line are ignored as comments.  The sequences "\\", "\{", "\}", "\[", "\]" and "\%" denote the characters "\", "{", "}", "[", "]", and "%" respectively.

Make sure that after a command there is a space between the command and normal text.  Otherwise, HWA for Dos will complain.


About HWA for Dos

The "Help Writer's Assistant"

 Copyright (C) 1991-1992 Rhys Weatherley

This topic describes the Help Writer's Assistant (HWA) version 1.01. HWA is intented to make the programmer's job easier when writing help files for use with Windows 3.0 applications.  It takes as input a plain ASCII text file that contains help formatting commands that are similar to the commands of TeX and LaTeX.  It writes out RTF files that are suitable for use with the SDK's Help Compiler.

HWA is protected by the GNU General Public License (version 1), a copy of which is available from the author.  Full source code is available.   Comments about the program and the source code can be sent to the author at one of the following addresses:

 AARNet/Internet: rhys@cs.uq.oz.au

 Aust. Post:	 Rhys Weatherley

 5 Horizon Drive

  Jamboree Heights  QLD  4074

  Australia

Any RTF files that are generated by this program can be distributed freely, as long as it is understood that the author of HWA is not liable in any way for their suitability or otherwise.  You may modify the file "HEADER.RTF" in this package for your own purposes only for use in generating RTF files. You may distribute any HWA source input files in the same way as generated RTF files, but this program CANNOT be included to process them.  If you wish to distribute HWA source files, then you are encouraged to state that they can be formatted using HWA version 1.01 or later, and you should also distribute a pre-formatted RTF file.

NOTE:To run HWA for Dos the HEADER.RTF file created by Options|Create HEADER.RTF needs to be in the HWA for Dos directory.


What is shareware?!?

Shareware is a system where you get to try out a program for a period of time (in this case 30 days), after which, if you decide to continue using the product, you must legally pay the author the amount he or she asks for  (in this case $40NZ).  Shareware products are generally very good quality products, and offer the user a chance to try out a product before they buy it.

See Also:

How to Register


Why Register?

Registration of HWA for Windows gives you many added bonuses apart from the fact that you are legally and morally being correct in registering it if you are using it.

You get:

A disk containing version 1.0 when it is released.

A free upgrade to version 2.0. (Cost includes shipping)

Free technical support for the lifetime of the product. (A separate email address will be given to you on the letter sent to you after you have registered.)

All this for only $40NZ!!  I have made the price low (approx $20US) so that users from other countries can afford a Bank Check or Visa and to send the letter to New Zealand for around the price of competing products (approx $25US).


How to Register

To register Help Writer's Assistant for Windows complete the following steps:

You can pay via VISA [image] or via a Bank Cheque.

Complete the registration form (also in the file HWAREG.TXT)

Write a bank check out to Stefan Olson. (If you are not paying by Visa)

Send it to:

 HWA for Windows

 4 Anaru Place

 Palmerston North

 New Zealand

If you would like to send your registration form via fax please contact me for the number to send it to.

The day I receive your registration I will enter you in my database and send you out a letter (or fax you  - please check with me if you would like your registration number faxed.) with your user name and serial no.  You will be sent version 1.0 and version 2.0 soon as they are released.


Registration Form

Product Name: HWA for Windows

Version No: 1.0 - Beta III

Cost:

___ copies * $40NZ = ____

I would like to pay by: Cheque/Visa

If cheque:   A cheque is enclosed for $_____NZ

If visa:   Card Holder Name:__________________________      Card No:_________________________

  Expiry date: _____/____/19____

Terms/Conditions: I agree HWA/w is distributed as shareware.  No warranty exists, either express or implied.  No liability is assumed for any damage or loss resulting from the use of this program.  No claims are made regarding the accuracy of this program. The author reserves the right to change pricing in future versions.

I agree that HWA/w, if being used on more than one computer at a time in a commercial environment must have a licence for each computer.  (Site licences are available, and terms are open to discussion)

A letter will be sent to you providing you with your serial number and user name.  The final release of version 1.0 (if you don't already have it) will be sent to you for free of charge.  Version 2.0 will be sent to you as a free upgrade.  The serial number that you recieve will work on all future releases of HWA for Windows while it is being produced by Olson Software.

I agree that for users not in New Zealand, only bank cheques or VISA will be accepted.

Your signature below indicates your acceptance of these terms and conditions.

Signed: __________________________________________  Date: ______________

Full Name:_____________________________________

(Name you would like to have as your User Name)

Gender: M/F

Occupation:_____________________________________

Company:_______________________________________

Postal Address:___________________________________________________

City:___________________________________________

COUNTRY:__________________________________________

Home Phone: ______________      Work Phone: ______________

Fax No: ______________

Type and Speed of computer:____________________________

Type of display used:________________________

Internet/Compuserve address:____________________________

Preferred method of recieving Serial Number: Fax/Snail Mail

Preferred method of getting updates: Internet Mail/Compuserve/Snail Mail

Disk Size: 3.5"/5.25"

What would you like to see improved or added in HWA/w:

  Make Cheques Payable to:       Stefan Olson

  and mail along with form to:   HWA for Windows

                                 4 Anaru Place

                                 Palmerston North

                                 New Zealand

Thank you for your registration!!

Stefan Olson


Known Bugs

The Text|Font dialog, when there is no font selected doesn't display the font at all.

For bugs that will be fixed in future releases, please see Future Enhancements

If you do find a bug other that the ones listed here please fill out HWA.BUG and send it to the author..  If you do find a bug that I don't already know about, and you are an unregistered user, you will recieve $0.50NZ off your registration cost.  That means if you find 80 bugs you get a free registration!!


Disclaimer

HWA/w is distributed as shareware.  No warranty exists, either express or implied.  No liability is assumed for any damage or loss resulting from the use of this program.  No claims are made regarding the accuracy of this program. The author reserves the right to change pricing in future versions.


Copying Info

This program may be freely used and copied but may not be sold except for a nominal copying charge not to exceed US $10. This file should be included with all copies of HWA/w.  If you decide you use HWA/w after using it for 30 days you must register it.


Revison History

1.0 Beta I	 16/12/92	 First Beta Release

1.0 Beta II	 17/2/93	 Second Beta Release

1.0 Beta III	 1/5/93	 Third Beta Release


Future Enhancements

NOTE: This is not a list of promised features, only what I hope will be in the version, so you have an approximate idea of where the product is  going.

Beta 4	 Visual text editor

 Use of installation program to install.

 Better topic structure in memory

 More assertions (for Debugging version)

There will be 1 more beta release after that and will fix any bugs and add anything users want to see.

Version 2.0	 New MDI interface.  It will be based around help projects, and will automatically sort out many options for the help project file.

 Help Templates, which will be .HWT file and whenever it finds <app_name> it will insert the application name, that you will be able to define.  E.g: Your application is Resta.  Wherever there is <app_name> it will become Resta.

 Justification of text.

 Conversion to printable formats

 Direct reading and writing of RTF files

Sometime	 Saving as write format (this could be hard)

 Tables, so text can be lined up correctly

 Easy conversion of current documentation

 A tree view of your help file, and links.

 Full support for Windows NT (Threads, etc...)


About the Author

Stefan Olson is 16 years old and this is the third windows program he's written.  He hopes to get a job as a programmer one day in the future, and has many other windows programs waiting to be written.  These include: a disk cataloguer, a windows unarchiver and archiver, a screen capture program with the ability to save the captured picture to .Bmp...  He has written Resta, a screen saver for Windows.  He has written Quick Install, a powerful installation program for Windows.


How to Contact the Author

The author can be contacted through the Internet at (don't type the brackets): (stefan@olson.acme.gen.nz)

The author can be contacted through compuserve at (don't type the brackets): (>Internet:stefan@olson.acme.gen.nz)

I'd appreciate it if you'd send me a mail message if you have any comments or suggestions...

If you find a bug please send me a mail message with a filled in bug report.


Programs and books used to write this program

HWA/w was written in C++ using the Microsoft Foundation Classes - "The C++ API for Windows" and compiled using Microsoft C/C++ 7.0.

HWA/w was debugged using Microsoft Codeview 4.0 for Windows.

HWA/w's icons and dialogs were created using Borland Resource Workshop 1.02(comes with Turbo C++ for Windows)

HWA/w's documentation was written in HWA for Windows and then compiled using the Compile|Run command.. (i.e: converted to RTF (help file) format, using HWA for Dos before the RTF file was compiled using the Microsoft Help Compiler 3.10.)

Betas II and before were:

Written in C++ using a class library written by Rhys Weatherly and using Borland Turbo C++ for Windows 3.1.  HWA/w was degbugged using Borland Turbo Debugger for Windows 3.1

I used the Borland Windows API Guide and the Turbo C++ for Windows on-line help to find the correct commands.

I used Charles Petzold's "Programming Windows 2nd Edition" (Microsoft Press, 1990) to learn windows programming.

I used Peter Norton & Paul Yao's "Power Programming Techniques 2nd Edition" (Bantam Books, 1992)


Acknowledgements

Thanks to:

Rhys Weatherly	 For letting me take the HWA source and make a Windows version, and for writing a very good class library.

Hamish Mackenzie	 For the invaluable help he has given me, and the time he spent putting up with my silly questions.

Mum & Dad	 For letting me use the computer even when they wanted to!

Graham Codd	 For helping me with the registration code and the text editor

Amy Olson (my Sister)	 For designing HWA/w's icons and bitmaps.


Trademarks

Turbo C++ for Windows, Turbo Debugger for Windows and the Resource Workshop are  trademarks of Borland International.

Microsoft C/C++, Codeview, SDK (Software Development Kit), Windows, Write and the Help compiler are trademarks of Microsoft Corporation.


Caret

The caret is what some people might call the cursor, but it should not be called a cursor as the mouse cursor is in fact the cursor!  The caret it the little black box which indicates where you are in a control.